Start5 API Documentation
Rev. 0.2 (18.12.98)
©1998 A. Pemsel / Team5

General Notes

This document describes all usefull functions and procedures that may be called by PlugIns. If you find a bug or you have further questions feel free to send an eMail to apemsel@rosenheim.baynet.de

INI File Management

PlugIns may store configuration data or vars that need to be restored when Start5 is restarted in Start5's INI file. Please make sure you do not store too much data in this way so the INI file does not unnecessarily grow.
An entry in the INI file consists of a key or name and a value. The name may be a string of up to 255 characters and should begin with your PlugIn's name to avoid name conflicts. Start5's INI file system supports two different types of values: Strings and Integers.

SaveINI%:(name$,value%)

This procedure will either create a new entry or modify an existing one.

LoadINI%:(name$)

This function will return the current value of the entry name$ or 0 if there is no such entry.

SaveINI$:(name$,value$)

LoadINI$:(name$)

These two procedures / functions do the same for string values.

Utility procedures for thread handling

Note: The usage of these procedures requires that you are familiar with the way in which EPOC handles threads.

GetActiveThreads:

This will rebuild Start5's internal list of running applications. Afterwards the following global vars will be updated. TID means Thread ID:

• ActiveThread& contains the TID of the active thread (the thread that is in foreground). If Start5 is in the foreground it contains the TID of the application which is visible in the background of Start5.

• ActiveThreads% contains the number of active threads

• SysThreadId& contains the TID of the operating system's shell

• MyThreadId& contains Start5's TID. (If Start5 runs in multithreading mode it contains the TID of this thread)

• ThreadID&() contains the TID's of all running threads excluding those of threads that are hidden from the task bar.

SortActiveThreads:

This will sort ThreadID&() by the TID. Normally the following statement is true: The lower a TID is, the longer is the coresponding thread already running.

ExistThread&:(TID&)

Returns TID& if the Thread with this TID exists or 0 if it does not.

PlugIn Management System

Normally there is only one reason why a PlugIn needs to make use of these procedures - to store data global. One limitation of PlugIns is that there is no support for global vars. However, if it is absolutely necessary there is a way to store data global. Each PlugIn is assigned one LongInt var in PlugInGlobal%(). PlugIns may access it in the following way:

PlugInGlobal%(PlugInID%:("NAME"))

NAME needs to be the name of the PlugIn. The procedure PlugInID%:(name$) returns the PlugInID, a unique number for each installed PlugIn. Programmers should be very carefull in order not to destroy other PlugIn's data by accidentially using PlugInGlobal%() with a wrong ID. If you need more than one var it is suggested to store a pointer to an ALLOCated memory block in PlugInGlobal%().

The following other vars and procedures of the PlugIn Management System are available and might be usefull for advanced programmers:

• PlugIn$() contains a list of all installed PlugIns' names

• PlugInUR%() contains the PlugIns' update rates. You could access this to change the PlugIns update rate dynamically.

• PlugInWID%() contains the PlugIns' window IDs

• KMaxPlugIns% contains the maximum number of PlugIns (all other field vars mentioned above range from 1 to KMaxPlugIns%)

• RunPlugInProc:(name$) calls the procedure name$ in all PlugIns

• UpdatePlugIns:(UpdateRate%) calls the UPDATE procedure of all PlugIns that have an update rate of UpdateRate% or higher.
  Warning!: Do not call this from your own PlugIn's UPDATE routine or you will cause an endless loop.

Other usefull vars and procedures

These are some other usefull procedures and global vars:

• MyDir$ contains the directory where Start5 is installed

• InForeGround% is true (-1) when Start5 is in the foreground, false (0) when in background

• ScreenW%, ScreenH% contain the dimensions of the screen

• BarW%, BarH% contain the dimensions of the Start5 bar

• BarPosition% is 1 if Start5 is on the bottom of the screen, 2 when on the top

• SetBarPosition:(p%) needs to be used to change the position of the bar

• ShowBar: takes Start5 to the foreground and updates everything